home *** CD-ROM | disk | FTP | other *** search
/ PC Format (South-Africa) 2001 June / PCFJune.iso / mweb / MWEB Utils / ws295sdk.exe / Ws2sdkzp.exe / SAMPLES / VENDINST / README.TXT < prev    next >
Encoding:
Text File  |  1997-06-06  |  7.2 KB  |  191 lines
  1. This readme describes the implementation details necessary to customize the 
  2. execution of WS2Setup.exe and to properly install base service providers.
  3.  
  4.  
  5. VENDOR INSTALL DLLS
  6. -------------------
  7. Any vendor that wishes to explicitly prevent Microsoft TCP,IPX, SAP and/or
  8. DNS from being upgraded or installed, or complete installation of their
  9. own Provider (by calling WSCInstallProvider or WSCInstallNameSpace)
  10. prior to reboot, or hide the WS295 User Interface, must create a Vendor 
  11. Install Dll as described below:
  12.  
  13.  
  14. Vendor should create a REG_SZ (string) value named "VendorInstallDll"
  15. under the \WinSock 2 \ Setup key with the complete path of their 
  16. install dll PRIOR to invoking ws2setup.exe.  Ws2setup.exe will load this
  17. dll and call the following functions if they are found to be exported:
  18.  
  19. VendorInstallProvider
  20. ---------------------
  21. Receives a ptr to the all of the provider configuration functions
  22. in WS2_32.DLL necessary to install a service provider. Should return number 
  23. of service providers successfully installed, or -1 to indicate error. 
  24. See prototype which follows function descriptions.
  25.  
  26. VendorInstallNameSpace
  27. ----------------------
  28. Receives a ptr to the all of the name space provider configuration functions
  29. in WS2_32.DLL necessary to install a name space provider. Should return 
  30. number of name space providers successfully installed, or -1 to 
  31. indicate error. See prototype which follows function descriptions.
  32.  
  33. VendorGetSetupOptions
  34. ---------------------
  35. Receives a ptr to a structure of type VENDOR_WS2SETUP_OPTIONS in 
  36. which it can indicate whether they want Microsoft to try to install or
  37. upgrade Microsoft TCP,IPX,SAP and/or DNS and whether to hide the WS295 setup
  38. routine UI. See prototype which follows function descriptions.
  39.  
  40. VendorCompleteWS2Install
  41. ------------------------
  42. Receives a LONG, which if 0 indicates successful completion, otherwise
  43. error.  Vendor would typically signal their installer program of the 
  44. result here. See prototype below.
  45.  
  46.  
  47. Function Prototypes
  48. ------------------------
  49. typedef LONG (WSAAPI *PFNWSPROC)();
  50.  
  51. LONG
  52. WSAAPI
  53. VendorInstallProvider(
  54.     int (WSAAPI *pfnWSCDeinstallProvider)(),
  55.     int (WSAAPI *pfnWSCEnumProtocols)(),
  56.     int (WSAAPI *pfnWSCGetProviderPath)(),
  57.     int (WSAAPI *pfnWSCInstallProvider)()
  58.     );
  59.  
  60. LONG
  61. WSAAPI
  62. VendorInstallNameSpace(
  63.     int (WSAAPI *pfnWSCEnableNSProvider)(),
  64.     int (WSAAPI *pfnWSCInstallNameSpace)(),
  65.     int (WSAAPI *pfnWSCUnInstallNameSpace)()
  66.     );
  67.  
  68. VOID
  69. WSAAPI
  70. VendorGetSetupOptions(
  71.     LPVENDOR_WS2SETUP_OPTIONS  lpSetupOptions
  72.     );
  73.  
  74. VOID
  75. WSAAPI
  76. VendorCompleteWS2Install(
  77.     LONG lResult
  78.     );
  79.  
  80.  
  81. Setup.exe will initialize the dwSize field in the following struct 
  82. before calling VendorGetSetupOptions, so vendor dll will know what 
  83. version of struct it is working with. Default values are noted in
  84. the comments.
  85.  
  86. typedef struct _VENDOR_WS2SETUP_OPTIONS     // Defaults:
  87. {
  88.     DWORD   dwSize;                         // sizeof (VENDOR_WS2SETUP_OPTIONS)
  89.     DWORD   dwInstallMicrosoftTCP;          // WS2SETUP_INSTALL_COMPONENT
  90.     DWORD   dwInstallMicrosoftIPX;          // WS2SETUP_UPGRADE_COMPONENT
  91.     BOOL    bShowWS2SetupUI;                // TRUE
  92.     DWORD   dwInstallMicrosoftDNS;          // WS2SETUP_INSTALL_COMPONENT
  93.     DWORD   dwInstallMicrosoftSAP;          // WS2SETUP_DONT_INSTALL_COMPONENT
  94.     LPCSTR  lpszWSock32DllLegalCopyright;   // NULL
  95.  
  96. } VENDOR_WS2SETUP_OPTIONS, FAR *LPVENDOR_WS2SETUP_OPTIONS;
  97.  
  98.  
  99. The only structure field whose purpose is not obvious from its name is
  100. lpszWSock32DllLegalCopyright. lpszWSock32DllLegalCopyright can point at 1 or more 
  101. NULL-terminated strings, the last of which is to be terminated with 2 NULL 
  102. characters, i.e. "string1\0string2\0\string3\0\0". This value should be set 
  103. to all of the copyright string(s) of the vendor's proprietary WinSock 1.1 
  104. WSOCK32.DLL(s) (if any) that the vendor wishes to allow WinSock 2 to be forcibly
  105. installed over.
  106.  
  107. Normally, WS2Setup.exe will abort if it sees a non-Microsoft copyright string 
  108. in WSOCK32.DLL. If the copyright is non-Microsoft AND any portion of the 
  109. copyright string in WSOCK32.DLL contains the string passed in by the vendor,
  110. WS2Setup will continue as if it had found a Microsoft copyright string, and 
  111. will not abort.
  112.   
  113. The defined values to be passed in for WS2SETUP options are
  114.  
  115. #define WS2SETUP_DONT_INSTALL_COMPONENT 0
  116. #define WS2SETUP_INSTALL_COMPONENT      1
  117. #define WS2SETUP_UPGRADE_COMPONENT      2
  118.  
  119. WS2SETUP_DONT_INSTALL_COMPONENT means do not under any circumstances install
  120. the microsoft version of this component
  121.  
  122. WS2SETUP_INSTALL_COMPONENT means install the microsoft version of this 
  123. component if & only if a competing vendor's version of this product is not installed
  124.  
  125. WS2SETUP_UPGRADE_COMPONENT means upgrade the microsoft version of this 
  126. component if & only if it is already installed (no error otherwise)
  127.  
  128.  
  129. VSETUP.DLL UTILITY
  130. ------------------
  131. Compiling VSETUP.DLL as is provides a stub vendor-setup dll utility that displays dialog 
  132. boxes for each of the four VendorXxx() funcs. This allows vendors to
  133. install and configure their components within the context of setup.exe.
  134.  
  135. After compilation, set the VendorInstallDll registry value as shown:
  136.  
  137.   \Winsock2
  138.     \Setup
  139.         VendorInstallDll  REG_SZ  "<path>\vsetup.dll"
  140.  
  141. VENDOR README FILES
  142. -------------------
  143. Vendors that are redistributing Ws2setup should include a readme describing
  144. the behavior of their product and the relevant behavior of ws2setup.exe
  145.  
  146. Microsoft recommends that the following sections from the SDK readme.txt 
  147. in the root directory \WS295SDK be included (or modified as appropriate) in 
  148. your version of readme.txt:
  149.  
  150. "WS2SETUP.EXE AND MICROSOFT PROXY SERVER WINSOCK PROXY CLIENT",
  151. "WS2SETUP.EXE AND DCOM'95",
  152. "UNISTALLING WINSOCK 2" 
  153. and parts of "SETUP WINDOWS 95 RUN-TIME COMPONENTS" as appropriate.
  154.  
  155.  
  156. REGISTRY SETTINGS AND SERVICE PROVIDER INSTALLATION
  157. ---------------------------------------------------
  158. In addition to the guidelines above, transport or "base" service providers
  159. must configure the registry prior to execution of WS2Setup.exe to register 
  160. the existence of their provider with WinSock 2, as well as to help other vendors 
  161. determine appropriate courses of action in their setup routines.
  162.  
  163. Installed WinSock 2 service providers can be found in the registry under 
  164. HKEY_LOCAL_MACHINE
  165.     \System
  166.     \CurrentControlSet
  167.         \Services
  168.         \WinSock2
  169.            \Providers
  170.                \INET
  171.               \ProviderName  "Foo brand's TCP provider, etc"
  172.                \DECNet
  173.               \ProviderName  "Foo brand's DECNet provider, etc"
  174.                 \IPX
  175.                   \ProviderName  "Foo brand's IPX/SPX provider, etc"
  176.             
  177.             (etc.)
  178.  
  179. where each key under \Providers is derived from the address family 
  180. definitions in WinSock2.h. minus the leading "AF_" (i.e.  "AF_INET" 
  181. becomes "INET")
  182.  
  183. It is the responsibility of the provider to be installed to determine if a
  184. provider of the same address family is already installed, and to create the 
  185. proper key (if necessary) and set the ProviderName value as appropriate. 
  186. (The value of the ProviderName should be your company name or company and 
  187. product name)
  188.  
  189. Conversely, a service provider should remove their registry 
  190. ProviderName value as part of a proper uninstall routine.
  191.